home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / cmds.h < prev    next >
C/C++ Source or Header  |  2005-10-18  |  8KB  |  194 lines
  1. /**
  2.  * @file cmds.h Commands API
  3.  * @ingroup core
  4.  *
  5.  * Copyright (C) 2003 Timothy Ringenbach <omarvo@hotmail.com>
  6.  *
  7.  * This program is free software; you can redistribute it and/or modify
  8.  * it under the terms of the GNU General Public License as published by
  9.  * the Free Software Foundation; either version 2 of the License, or
  10.  * (at your option) any later version.
  11.  *
  12.  * This program is distributed in the hope that it will be useful,
  13.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15.  * GNU General Public License for more details.
  16.  *
  17.  * You should have received a copy of the GNU General Public License
  18.  * along with this program; if not, write to the Free Software
  19.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  20.  *
  21.  */
  22. #ifndef _GAIM_CMDS_H_
  23. #define _GAIM_CMDS_H_
  24.  
  25. #include "conversation.h"
  26.  
  27. /**************************************************************************
  28.  * @name Structures
  29.  **************************************************************************/
  30. /*@{*/
  31.  
  32. typedef enum _GaimCmdPriority GaimCmdPriority;
  33. typedef enum _GaimCmdFlag     GaimCmdFlag;
  34. typedef enum _GaimCmdStatus   GaimCmdStatus;
  35. typedef enum _GaimCmdRet      GaimCmdRet;
  36.  
  37. enum _GaimCmdStatus {
  38.     GAIM_CMD_STATUS_OK,
  39.     GAIM_CMD_STATUS_FAILED,
  40.     GAIM_CMD_STATUS_NOT_FOUND,
  41.     GAIM_CMD_STATUS_WRONG_ARGS,
  42.     GAIM_CMD_STATUS_WRONG_PRPL,
  43.     GAIM_CMD_STATUS_WRONG_TYPE,
  44. };
  45.  
  46. enum _GaimCmdRet {
  47.     GAIM_CMD_RET_OK,       /**< Everything's okay. Don't look for another command to call. */
  48.     GAIM_CMD_RET_FAILED,   /**< The command failed, but stop looking.*/
  49.     GAIM_CMD_RET_CONTINUE, /**< Continue, looking for other commands with the same name to call. */
  50. };
  51.  
  52. #define GAIM_CMD_FUNC(func) ((GaimCmdFunc)func)
  53.  
  54. typedef GaimCmdRet (*GaimCmdFunc)(GaimConversation *, const gchar *cmd,
  55.                                   gchar **args, gchar **error, void *data);
  56. typedef guint GaimCmdId;
  57.  
  58. enum _GaimCmdPriority {
  59.     GAIM_CMD_P_VERY_LOW = -1000,
  60.     GAIM_CMD_P_LOW      =     0,
  61.     GAIM_CMD_P_DEFAULT  =  1000,
  62.     GAIM_CMD_P_PRPL     =  2000,
  63.     GAIM_CMD_P_PLUGIN   =  3000,
  64.     GAIM_CMD_P_ALIAS    =  4000,
  65.     GAIM_CMD_P_HIGH     =  5000,
  66.     GAIM_CMD_P_VERYHIGH =  6000,
  67. };
  68.  
  69. enum _GaimCmdFlag {
  70.     GAIM_CMD_FLAG_IM               = 0x01,
  71.     GAIM_CMD_FLAG_CHAT             = 0x02,
  72.     GAIM_CMD_FLAG_PRPL_ONLY         = 0x04,
  73.     GAIM_CMD_FLAG_ALLOW_WRONG_ARGS = 0x08,
  74. };
  75.  
  76.  
  77. /*@}*/
  78.  
  79. #ifdef __cplusplus
  80. extern "C" {
  81. #endif
  82.  
  83. /**************************************************************************
  84.  * @name Commands API
  85.  **************************************************************************/
  86. /*@{*/
  87.  
  88. /**
  89.  * Register a new command with the core.
  90.  *
  91.  * The command will only happen if commands are enabled,
  92.  * which is a UI pref. UIs don't have to support commands at all.
  93.  *
  94.  * @param cmd The command. This should be a UTF8 (or ASCII) string, with no spaces
  95.  *            or other white space.
  96.  * @param args This tells Gaim how to parse the arguments to the command for you.
  97.  *             If what the user types doesn't match, Gaim will keep looking for another
  98.  *             command, unless the flag @c GAIM_CMD_FLAG_ALLOW_WRONG_ARGS is passed in f.
  99.  *             This string contains no whitespace, and uses a single character for each argument.
  100.  *             The recognized characters are:
  101.  *               'w' Matches a single word.
  102.  *               'W' Matches a single word, with formatting.
  103.  *               's' Matches the rest of the arguments after this point, as a single string.
  104.  *               'S' Same as 's' but with formatting.
  105.  *             If args is the empty string, then the command accepts no arguments.
  106.  *             The args passed to callback func will be a @c NULL terminated array of null
  107.  *             terminated strings, and will always match the number of arguments asked for,
  108.  *             unless GAIM_CMD_FLAG_ALLOW_WRONG_ARGS is passed.
  109.  * @param p This is the priority. Higher priority commands will be run first, and usually the
  110.  *          first command will stop any others from being called.
  111.  * @param f These are the flags. You need to at least pass one of GAIM_CMD_FLAG_IM or
  112.  *          GAIM_CMD_FLAG_CHAT (can may pass both) in order for the command to ever actually
  113.  *          be called.
  114.  * @param prpl_id This is the prpl's id string. This is only meaningful is the proper flag is set.
  115.  * @param func This is the function to call when someone enters this command.
  116.  * @param helpstr This is a whitespace sensitive, UTF-8, HTML string describing how to use the command.
  117.  *                The preferred format of this string shall be the commands name, followed by a space
  118.  *                and any arguments it accpets (if it takes any arguments, otherwise no space), follow
  119.  *                by a colon, two spaces, and a description of the command in sentence form. No slash
  120.  *                before the command name.
  121.  * @param data User defined data to pass to the GaimCmdFunc
  122.  * @return A GaimCmdId. This is only used for calling gaim_cmd_unregister.
  123.  *         Returns @c NULL on failure.
  124.  */
  125. GaimCmdId gaim_cmd_register(const gchar *cmd, const gchar *args, GaimCmdPriority p, GaimCmdFlag f,
  126.                              const gchar *prpl_id, GaimCmdFunc func, const gchar *helpstr, void *data);
  127.  
  128. /**
  129.  * Unregister a command with the core.
  130.  *
  131.  * All registered commands must be unregistered, if they're registered by a plugin
  132.  * or something else that might go away. Normally this is called when the plugin
  133.  * unloads itself.
  134.  *
  135.  * @param id The GaimCmdId to unregister.
  136.  */
  137. void gaim_cmd_unregister(GaimCmdId id);
  138.  
  139. /**
  140.  * Do a command.
  141.  *
  142.  * Normally the UI calls this to perform a command. This might also be useful
  143.  * if aliases are ever implemented.
  144.  *
  145.  * @param conv The conversation the command was typed in.
  146.  * @param cmdline The command the user typed (including all arguments) as a single string.
  147.  *            The caller doesn't have to do any parsing, except removing the command
  148.  *            prefix, which the core has no knowledge of. cmd should not contain any
  149.  *            formatting, and should be in plain text (no html entities).
  150.  * @param markup This is the same as cmd, but is the formatted version. It should be in
  151.  *               HTML, with < > and &, at least, escaped to html entities, and should
  152.  *               include both the default formatting and any extra manual formatting.
  153.  * @param errormsg If the command failed errormsg is filled in with the appropriate error
  154.  *                 message. It must be freed by the caller with g_free().
  155.  * @return A GaimCmdStatus indicated if the command succeeded or failed.
  156.  */
  157. GaimCmdStatus gaim_cmd_do_command(GaimConversation *conv, const gchar *cmdline,
  158.                                   const gchar *markup, gchar **errormsg);
  159.  
  160. /**
  161.  * List registered commands.
  162.  *
  163.  * Returns a GList (which must be freed by the caller) of all commands
  164.  * that are valid in the context of conv, or all commands, if conv is
  165.  * @c NULL. Don't keep this list around past the main loop, or anything else
  166.  * that might unregister a command, as the char*'s used get freed then.
  167.  *
  168.  * @param conv The conversation, or @c NULL.
  169.  * @return A GList of const char*, which must be freed with g_list_free().
  170.  */
  171. GList *gaim_cmd_list(GaimConversation *conv);
  172.  
  173. /**
  174.  * Get the help string for a command.
  175.  *
  176.  * Returns the help strings for a given command in the form of a GList,
  177.  * one node for each matching command.
  178.  *
  179.  * @param conv The conversation, or @c NULL for no context.
  180.  * @param cmd The command. No wildcards accepted, but returns help for all
  181.  *            commands if @c NULL.
  182.  * @return A GList of const char*s, which is the help string
  183.  *         for that command.
  184.  */
  185. GList *gaim_cmd_help(GaimConversation *conv, const gchar *cmd);
  186.  
  187. /*@}*/
  188.  
  189. #ifdef __cplusplus
  190. }
  191. #endif
  192.  
  193. #endif /* _GAIM_CMDS_H_ */
  194.